#
# overflowR: An R package to pull data from the StackOverflow API
# author: Shane Conway <shane.conway@gmail.com>
#
# This is released under a GPL license.
#
# Documentation was created using roxygen:
# roxygenize('overflowR', roxygen.dir='overflowR', copy.package=FALSE, unlink.target=FALSE)
#
###############################################################################

#' Pull data from the StackExchange API.
#'
#' \code{getSOData} pulls data from the StackExchange API.
#'
#' @param type		Specifies the API data to return 
#' @param id		A specific record id (e.g. for a user) 
#' @param page.num	The page to request
#' @param page.size	The size of each page request 
#' @param api.key 	The API key to be used in the application 
#' @return json results from API
#' @keywords data
#' @author Shane Conway \email{shane.conway@@gmail.com}
#' @references
#' \url{http://stackapps.com/}
#' @seealso \code{\link{get.recursive.data}} 
#' @examples
#' getSOData(type="tags", page.num=2)
getSOData <- function(type="stats", id=NULL, page.num=NULL, page.size=100, 
	site="stackoverflow", api.version="1.0", tagged=NULL, api.key="iv1qWOxcwkaKg53RJIXh-A") { 
	if(api.key == "") stop("Pulling data from the StackExchange requires an API key.  See the configuration details in vignette('overflowR').")
	url.string <- paste(
			"http://api.", site, ".com/", api.version, "/", 
			type, "/", 
			id, 
			"?", 
			"page=", page.num, "&",
			"tagged=", tagged, "&",
			"pagesize=", page.size, "&",
			"key=", api.key, 
			sep="") 
	print(url.string)
	x <- try(fromJSON(paste(readLines(z <- gzcon(url(url.string))), collapse="")))
	close(z)
	x
}

#' Pull data from the StackExchange API
#'
#' \tabular{ll}{
#' Package: \tab overflowR\cr
#' Type: \tab Package\cr
#' Version: \tab 0.1\cr
#' Date: \tab 2010-06-23\cr
#' License: \tab GPL (>= 2)\cr
#' LazyLoad: \tab no\cr
#' }
#'
#' Pull data from the StackExchange API
#' 
#' @name overflowR-package
#' @aliases overflowR
#' @docType package
#' @title Pulls data from StackExchange API.
#' @author Shane Conway \email{shane.conway@@gmail.com}
#' @references
#' \url{http://stackapps.com/}
#' @keywords package
NULL
